Walkthrough 3-3: Add request and response details

In this walkthrough, you add information about each of the methods to the API specification. You will:

·       Use API fragments from Exchange.

·       Add a data type and use it to define method requests and responses.

·       Add example JSON requests and responses.

·       Test an API and get example responses.

  

Starting file

If you did not complete the previous walkthrough, you can get a starting file here. This file is also located in the solutions folder of the student files ZIP located in the Course Resources.

Add data type and example fragments from Exchange

1.     Return to API Designer.

2.     In the file browser, click the Exchange dependencies button.

 

3.     Click the Add button.

 

4.     In the Exchange Dependencies dialog box, select the Training: American Flight Data Type and the Training: American Flights Example.

 

5.     Click the Add 2 dependencies button.

6.     In the dependencies list, click the Training: American Flight Data Type option menu and review the menu options.

  

7.     Click the Files button (above the Exchange dependencies button).

8.     Expand the exchange_modules section until you see AmericanFlightDataType.raml.

9.     Click AmericanFlightDataType.raml and review the code.

 

10.  In the file browser, click the options menu button next to AmericanFlightsDataType.raml and select Copy path to clipboard.

 

Define an AmericanFlight data type for the API

11.  Return to american-flights-api.raml.

12.  Near the top of the code above the /flights resource, add a types element.

13.  Indent under types and add a type called AmericanFlight.

14.  Add the !include keyword and then paste the path you copied.

Note: You can also add the path by navigating through the exchange_modules folder in the shelf.

Specify the /flights:get method to return an array of AmericanFlight objects

15.  Go to a new line of code at the end of the /flights get method and indent to the same level as queryParameters.

16.  In the shelf, click responses > 200 > body > application/json > type > AmericanFlight.

Note: Enter the responses element manually if it doesn't appear in the shelf.

 

17.  Set the type to be an array of AmericanFlight objects: AmericanFlight[].

 

Add an example response for the /flights:get method

18.  In the file browser, locate AmericanFlightsExample.raml in exchange_modules and review the code.

 

19.  In the file browser, click the options menu next to AmericanFlightsExample.raml and select Copy path to clipboard.

20.  Return to american-flights-api.raml.

21.  In the editor, go to a new line after the type declaration in the /flights:get 200 response (at the same indentation as type).

22.  In the shelf, click examples.

23.  Add a key called output.

24.  Add the !include keyword and then paste the path you copied.

Note: You can also add the path by navigating through the exchange_modules folder in the shelf.

 

Review and test the /flights:get resource in API console

25.  In API console, click the /flights:get method.

26.  In the response information, look at the type information.

  

27.  In the response information, ensure you see the example array of AmericanFlight objects.

  

28.  Click the Try it button and click Send; you should now see the example response with two flights.

Specify the /{ID}:get method to return an AmericanFlight object

29.  In the editor, indent under the /{ID} resource get method.

30.  In the shelf, click responses > 200 > body > application/json > type > AmericanFlight.

 

Define an example response for the /flights:get method in a new folder

31.  In the file browser, click the add button and select New folder.

 

32.  In the Add new folder dialog box, set the name to examples and click Create.

33.  In the settings drop-down menu in the upper-right corner, select Import.

 

34.  In the Import dialog box, leave File or ZIP selected and click the Choose file button.

35.  Navigate to your student files and select the AmericanFlightExample.raml file in the resources/examples folder and click Open.

36.  In the Import dialog box, click Import; you should see the new file in API Designer.

37.  Review the code.

38.  In the file browser, drag AmericanFlightExample.raml into the examples folder.

  

Add an example response for the /{ID}:get method

39.  Return to american-flights-api.raml.

40.  In the editor, go to a new line after the type declaration in {ID}:/get (at the same indentation).

41.  In the shelf, click examples.

Note: Enter the examples element manually if it doesn't appear in the shelf.

42.  Add a key called output.

43.  Add an include statement and include the example in examples/AmericanFlightExample.raml.

 

Review and test the /{ID}:get resource in API console

44.  In API console, return to the /{ID}:get method; you should now see the response will be of type AmericanFlight.

  

45.  In the response information, ensure you see the example AmericanFlightExample data.

46.  Click the Try it button, enter an ID, and click Send; you should now see the example flight data returned.

  

Specify the /flights:post method request to require an AmericanFlight object

47.  In the editor, indent under the /flights post method.

48.  In the shelf, click body > application/json > type > AmericanFlight.

 

Define an example request body for the /flights:post method

49.  Return to AmericanFlightExample.raml and copy all the code.

50.  In the file browser, click the add button next to the examples folder and select New file.

51.  In the Add new file dialog box, set the following values:

·       Version: RAML 1.0

·       Type: Example

·       File name: AmericanFlightNoIDExample.raml

52.  Click Create.

53.  Delete any code in the new file and then paste the code you copied.

54.  Delete the line of code containing the ID.

 

55.  Return to american-flights-api.raml.

56.  In the post method, go to a new line under type and add an examples element.

57.  Add a key called input.

58.  Add an include statement and include the example in examples/AmericanFlightNoIDExample.raml.

 

Specify an example response for the /flights:post method

59.  Go to a new line of code at the end of the /flights:post method and indent to the same level as body.

60.  Add a 201 response of type application/json.

Note: Enter the responses element manually if it doesn't appear in the shelf.

 

61.  In the shelf, click example.

62.  Indented under example, add a message property equal to the string: Flight added (but not really).

 

Review and test the /flights:post resource in API console

63.  In API console, return to the /flights:post method.

64.  Look at the request information; you should now see information about the body - that it is type AmericanFlight and it has an example.

  

65.  Click the Try it button; in the Body section you should see the example request body.

  

66.  Click the Send button; you should now get a 201 response with the example message.

  

67.  In the body, remove the emptySeats property.

  

68.  Click Send again; you should get a 400 Bad Request response and a message that the emptySeats key is required.

  

69.  Add the emptySeats property back to the body.